home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / JPDOOR32.ARJ / MULTI.DOC < prev    next >
Text File  |  1992-02-26  |  16KB  |  393 lines
  1.  
  2.            ┌──────────────────────────────────────────────┐
  3.            │             MOTOR CITY SOFTWARE              │
  4.            │   ┌──────────────────────────────────────┐   │
  5.            │   │       JPDoor - Version 3.1 SE        │   │
  6.            │   │        Copyright 1990 - 1992         │   │
  7.            │   │            ┌──────────┐              │   │
  8.            │   │            │\         │              │   │
  9.            │   │            │ \        │              │   │
  10.            │   │            │  \   P   │              │   │
  11.            │   │            │   \  A   │              │   │
  12.            │   │            │   │  S   │              │   │
  13.            │   │            │   │  C   │              │   │
  14.            │   │     5.5    │   │  A   │    6.0       │   │
  15.            │   │            │  o│  L   │              │   │
  16.            │   │            │   │      │              │   │
  17.            │   │            \   │──────┘              │   │
  18.            │   │             \  │                     │   │
  19.            │   └──────────────\ │─────────────────────┘   │
  20.            │      The Ultimate \│ Door Writing Unit.      │
  21.            └────────────────────┴─────────────────────────┘
  22.  
  23.  
  24.  
  25.   This file contains information on writing doors that work in a multi-node
  26.   environment. While your door may not be multi-player, we would recommend
  27.   that you read over the following information anyways.
  28.  
  29.  
  30.   With the number of Multi-Node BBS's steadily increasing, we felt it was
  31.   very important to make it easy on the programmer to make his doors multi-
  32.   node aware.  This release of JPDoor has many new features that make it easy
  33.   to write programs which work in a multi-node environment, even if you are
  34.   not running multi-node yourself.  We have taken this one step further, in
  35.   that you can easily write doors which allow players to compete head-to-head!
  36.  
  37.   While some of this may sound complex, it really is quite simple.
  38.  
  39.   JPDoor will only allow multi-player games on RemoteAccess V 1.xx and
  40.   QuickBBS V 2.75. Future versions will also include full support for PCBoard.
  41.   SHARE MUST BE LOADED!
  42.  
  43.   Some of the multi-node capabilities included are:
  44.  
  45.   - Listing Other Users Currently Online
  46.   - Sending Online Messages to other users
  47.   - Determining the node number that the current user is logged onto
  48.   - Determining who is logged onto other nodes
  49.   - File/Record locking routines so your door can run on more than one node
  50.     at a time
  51.   - A method to ensure that your door is only run on one node at a time if
  52.     need be
  53.   - The ability for two nodes to pass data back and forth
  54.  
  55.   This document is going to try to explain how to write a door which allows
  56.   two players, and passes game data back and forth between them.  These
  57.   routines have been tested extensively, and while they appear to be working
  58.   fine, there exists a possibility that there are systems which may have
  59.   problems.  Because of this, we will be working closely with anyone having
  60.   problems.  If problems are discovered, then beta versions will be made
  61.   available to any registered user who requests it.
  62.  
  63.  
  64.   To start with, some basic concepts...
  65.  
  66.         Multi-player doors will only work with QBBS 2.75 or RA 1.xx
  67.         All data is passed in a file called JPDOOR.USE which will be
  68.         created in the system directory pointed to by either the RA
  69.         or QUICK environment variable.
  70.  
  71.         JPDoor has defined the structure for this file as follows:
  72.  
  73. TYPE
  74.    JPUseData        = Array[1..2048] of Byte;
  75.    JPUSErecord      = record
  76.                       Name           : String[35];
  77.                       Line           : Byte;
  78.                       DoorName       : String[20];
  79.                       Status         : Byte;
  80.                       MaxPlayers     : Byte;
  81.                       Filler         : Array[1..13] of byte;
  82.                       MultiNode      : Boolean;
  83.                       PID            : Integer;
  84.                       Data           : JPUseData;
  85.                     End;
  86.  
  87.                     { Status Byte :  0 - New Record Added   }
  88.                     {                1 - New Data Written   }
  89.                     {                2 - Data Has Been Read }
  90.  
  91. Var
  92.   JPUse         : JPUseRecord;   { Variable to hold MY record}
  93.   JPUseOther    : JPUseRecord;   { Variable to hold OTHER users record }
  94.  
  95.         Lets look at each field :
  96.  
  97.         Name       - This is the name of the user currently online
  98.  
  99.         Line       - This is the node number the user is on. This does
  100.                      not default to 1 like the dorinfo1.def does, and you
  101.                      can get the users node with the function GetNode.
  102.                      GetNode will simply search USERON.BBS for the users
  103.                      name as defined in dorinfo1.def, and return the actual
  104.                      node he is loggend onto.
  105.  
  106.         DoorName   - This is the name of your door. Its best to keep this to
  107.                      15 characters or less. When JPDoor's Whoson procedure is
  108.                      called, it will display this so other users can see that
  109.                      your door is in use.
  110.  
  111.         Status     - This is used internally, and you need not worry about it.
  112.                      The following values are used :
  113.                         0 - New Record Added
  114.                         1 - New Data Written
  115.                         2 - Data Has Been Read
  116.  
  117.         MaxPlayers - This contains the maximum number of users who can play
  118.                      at one time.  Currently, JPDoor will only support 2
  119.                      players, but this will be increased in future versions.
  120.  
  121.         MultiNode  - True if your door allows more than one user to run the
  122.                      door at the same time.
  123.  
  124.         PID        - If your Door is a multi-player door, then you MUST apply
  125.                      for a Product ID code. You must be registered in order
  126.                      to receive one. In order to test your door, use a PID of
  127.                      0. If you attempt to use any other value, it will abort!
  128.  
  129.         Data      - This is where all the data is passed back and forth between
  130.                     two nodes. This is explained in detail below.
  131.  
  132.  
  133. A note about PIDs.
  134.                      The PID is used to ensure that you only try to read data
  135.                      written by YOUR door on another node. You dont want a
  136.                      battleship door reading a data file from an X's and O's
  137.                      door etc...  The PID is validated internally by JPDoor.
  138.                      The Value of 0 is for test purposes only, as we do not
  139.                      want to force you to register BEFORE you can test it.
  140.                      If you release a multi-player door using a 0 for a PID,
  141.                      then you run the risk of it conflicting with other doors!
  142.                      You will need a PID for each and every different multi-
  143.                      player game you write.
  144.  
  145.                      There is no fee for registering a PID, and there is no
  146.                      limit to the number of PIDs you may register, but you
  147.                      must be a registered user of JPDoor.
  148.  
  149.                      PID 0 is ONLY for testing purposes, and you are expected
  150.                      to register JPDoor and request a PID BEFORE you release
  151.                      your door.
  152.  
  153.  
  154. How it all works.
  155.  
  156.  
  157.         First, you need to decide what data you wish to pass back and forth.
  158.         Define a structure that is exactly 2048 bytes in size. An example
  159.         from my BattleShips door follows:
  160.  
  161.  TYPE
  162.    Grid          = Array[1..9,0..9] of Char; { Letter,Number }
  163.  
  164.    NodeData      = Record
  165.         Status     : Byte;
  166.         PlayerName : String[25];
  167.         SeaGrid    : Grid;
  168.         ShotN,
  169.         ShotL      : Byte;
  170.         ShipHits   : Array[1..6] of byte;
  171.         ChatLine   : String[78];
  172.         Local      : Boolean;
  173.         Filler     : Array[1..1843] of Byte;  {this is added to ensure that}
  174.                                               { the record is exactly 2048 }
  175.                                               { bytes in length}
  176.    End;
  177.  
  178.  
  179.         Once you have defined this structure, you need to be able to reference
  180.         it two ways. You need to be able to modify each field, and also be
  181.         able to reference it within the JPUseRecord. This is accomplished by
  182.         using pointers.
  183.  
  184.         You must also remember that you need to reference YOUR nodes data, as
  185.         well as the OTHER nodes data.
  186.  
  187.  
  188.   Var
  189.     JPD           : JPUseData;  { MY nodes Data as a field in JPUseRecord}
  190.     OJPD          : JPUseData;  { OTHER nodes data as a field in JPUseRecord}
  191.     NDPtr         : ^NodeData;  { My Nodes Data a I defined it}
  192.     ONDPtr        : ^NodeData;  { Other nodes data as I defined it}
  193.  
  194.  
  195.         Now JPD and OJPD are an Array[1..2048] of Byte;
  196.         NDPtr and ONDPtr are pointers to the Type we defined above.
  197.  
  198.         All of these structures occupy the same amount of space, 2048 bytes.
  199.         We can now tell our program that NDPtr points to the same location in
  200.         memory where the variable JPD is stored, and ONDPtr points to the same
  201.         location in memory where the variable OJPD is stored. If your not
  202.         familiar with pointers, don't worry, I'm no pro either <grin>.
  203.         Basically what we are doing, is saying that NDPtr points to the
  204.         location where the variable JPD is located in memory. Because they
  205.         are the same size, we can now reference the same data in two ways!
  206.  
  207.            NDPtr := @JPD;       {OUR nodes data}
  208.            ONDPtr := @OJPD;     {OTHER nodes data}
  209.  
  210.         If we want to put the users name into the JPDoor.Use file, we simply
  211.         refer to the name field defined in JPUseRecord as JPD.NAME
  212.  
  213.         To reference a field in OUR defined structure, we use the pointer.
  214.         For example if I wish to pass a short note to the user on the other
  215.         node, I can use the CHATLINE field I defined in MY structure.
  216.  
  217.                 NDPtr^.ChatLine := 'Hi there...';
  218.  
  219.         Because this points to JPD which is 2048 bytes in size, and ChatLine
  220.         starts at 126 bytes into MY structure, is is saved in the same memory
  221.         location as JPD, but at offset 126.
  222.         Now JPD contains this string starting at byte 126.
  223.  
  224.         Like I said, it may sound confusing, but don't worry about it. Its
  225.         kinda like driving a car, you don't have to understand how it works
  226.         in order to use it, Afterall, thats what JPDoor is all about, making
  227.         it easy to do things you may not understand!
  228.  
  229.  
  230.  
  231. Adding a user to JPDOOR.USE
  232. ---------------------------
  233.  
  234. Function JPUseAdd : Boolean;
  235.  
  236.         In your door, you need to add the user information to the JPDOOR.USE
  237.         file. This is done with the JPUseAdd function. If JPDOOR.USE does
  238.         not exist, it will be created. This function will count the number of
  239.         nodes by counting the number of records in your USERON.BBS and one
  240.         record will be added to JPDOOR.USE for each one in USERON.BBS.
  241.  
  242.         Here is a sample from my MAIN code:
  243.  
  244. BEGIN          (* M A I N *)
  245.    ASSIGN(output,'') ;
  246.    REWRITE(output) ;
  247.    InitVars ;
  248.    GetDorInfo('1',DropPath) ;
  249.    NDPtr := @JPD;                       {Set the pointer to point to JPD}
  250.    ONDPtr := @OJPD;
  251.    FillChar(NDPtr^,SizeOf(NDPtr^),#0);  {Fill the memory location with Nulls}
  252.    JPUse.Pid := 0;                      {Set Your PID - 0 if not registered}
  253.    JPUse.Name := UserName;
  254.    JPUse.MultiNode := True;
  255.    JPUse.DoorName := 'BattleShip';
  256.    JPUse.Line := GetNode;
  257.    NDPtr^.Status := 1;
  258.    JPUse.MaxPlayers := 2;
  259.    JPUse.Data := JPD;                { Now move JPD into the JPUse.Data field}
  260.    If Not JPUseAdd then
  261.    Begin
  262.       CRLF ;
  263.       Display(0,15,0,'Motor City Battle Ships allows for two players at once,') ;
  264.       Display(0,15,0,'and there are currently two people playing.') ;
  265.       CRLF ;
  266.       HALT(0) ;
  267.    End;
  268.  
  269.         You will notice that I set JPUse.MaxPlayers to 2 players. When JPUseAdd
  270.         is called, it counts the number of users already in JPDoor.Use with the
  271.         same PID, and if there are already MaxPlayers playing, JPUseAdd will
  272.         NOT add you, and will return False.
  273.  
  274.  
  275.  
  276. Removing a user from JPDOOR.USE
  277. -------------------------------
  278.  
  279. Procedure JPUseExit;
  280.  
  281.         When the user exists the door, under ANY circumstances, you MUST make
  282.         sure you remove him from the JPDOOR.USE file.  This is done by adding
  283.         the JPUseExit procedure to your Terminate procedure as follows:
  284.  
  285.  
  286.  
  287. Procedure Terminate(n:byte) ;
  288. begin
  289.   JPUseExit;                    {This ensures that the user is removed!}
  290.   case n of
  291.     0 : begin
  292.           CloseGame ;
  293.           LastComments ;
  294.         end ;
  295.     1 : begin
  296.           CloseGame ;
  297.           Writeln('■ Carrier lost') ;
  298.         end ;
  299.     2 : begin
  300.           CloseGame ;
  301.           Writeln('■ Time limit exceeded') ;
  302.         end ;
  303.     3 : begin
  304.           CloseGame ;
  305.           Writeln('■ User inactive') ;
  306.         end ;
  307.     4,
  308.     5,
  309.     6 : begin
  310.         end ;
  311.     7 : begin
  312.           CloseGame ;
  313.           Writeln('■ CTS timeout error') ;
  314.         End ;
  315.     else CloseGame ;
  316.   end ;
  317. end ;
  318.  
  319.  
  320.  
  321.  
  322. Updating Data in JPDOOR.USE
  323. ---------------------------
  324.  
  325. Procedure JPUseUpdate;
  326.  
  327.         Data is passed to the other node by updating your JPUse.Data field,
  328.         so that the other node can read it. It is similar to the JPUseAdd
  329.         function except this is a procedure, and does not return any values.
  330.         You may find it easier to create a PlayerUpdate procedure as I did
  331.         in BattleShips:
  332.  
  333.  
  334. Procedure UpDateMyData;
  335. Begin
  336.   NDPtr^.Local := Local;
  337.   If Not SendChat then NDPtr^.ChatLine := '';
  338.   SendChat := False;
  339.   JPUse.Data := JPD;
  340.   JPUseUpDate;
  341. End;
  342.  
  343.  
  344.         Your code would update any relevent fields, then call this procedure.
  345.         When you Update your data, JPUse.Status will be set to 1 signifying
  346.         that new data has been written to the file.
  347.  
  348.  
  349.  
  350. Getting Other Users Data from JPDOOR.USE
  351. ----------------------------------------
  352.  
  353.  
  354. Function JPUseGet : Boolean;
  355.  
  356.         JPUseGet will scan the JPDOOR.USE file for another user (it checks
  357.         the username) with the SAME PID as your door. If one is found, and
  358.         new data is read (JPUse.Status = 1) then JPUseGet returns TRUE and
  359.         the other users data is stored in the variable JPUseOther.
  360.         JPUseOther is exactly the same as JPUse, but is a seperate variable
  361.         to hold the other players data. Both are defined in JPDoor.
  362.         If there is no other user, then JPUseGet returns false, and the
  363.         variable is filled with nulls. If it finds a user, but no new data
  364.         is found, it returns false, and contains the same data as before the
  365.         call was made.
  366.  
  367.         If you are waiting for the other player to take his turn, you may
  368.         simply keep calling this funtion until it returns TRUE.
  369.  
  370.         The other players data is read the same as you write your data.
  371.  
  372.  
  373.         If JPUseGet then
  374.         Begin
  375.           OJPD := JPUseOther.Data;  { Put OTHER users data into OJPD}
  376.         End;
  377.  
  378.         To get his name         :    JPUseOther.Name
  379.         To Get his Node#        :    JPUseOther.Line
  380.         To Get his Chatline     :    ONDPtr^.ChatLine
  381.  
  382.         etc...
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.